RtCreateProcess

RtCreateProcess creates and starts a new RTSS process. The new RTSS process runs the specified RTSS executable file.

Syntax

BOOL RtCreateProcess(
    LPCTSTR lpApplicationName,
    LPTSTR lpCommandLine,
    LPSECURITY_ATTRIBUTES lpProcessAttributes,
    LPSECURITY_ATTRIBUTES lpThreadAttributes,
    BOOL bInheritHandles,
    DWORD dwCreationFlags,
    LPVOID lpEnvironment,
    LPCTSTR lpCurrentDirectory,
    LPSTARTUPINFO lpStartupInfo,
    LPPROCESS_INFORMATION lpProcessInformation
);

Parameters

lpApplicationName

Pointer to a null-terminated string that specifies the module to execute. The string must specify the full path and file name of the module to execute.

The lpApplicationName parameter can be NULL. In that case, the module name must be the first white space-delimited token in the lpCommandLine string.

The specified module must be an RTSS application.

lpCommandLine

Pointer to a null-terminated string that specifies the command line to execute.

The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line.

If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the module to execute, and *lpCommandLine specifies the command line. The new process can use GetCommandLine to retrieve the entire command line. C runtime processes can use the argc and argv arguments.

If lpApplicationName is NULL, the first white-space - delimited token of the command line specifies the module name. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin (see the explanation for the lpApplicationName parameter). If the file name does not contain an extension, .rtss is appended.

lpProcessAttributes

Ignored. Pointer to a Win32 SECURITY_ATTRIBUTES structure that specifies the security descriptor for the process. If lpProcessAttributes is null, the process gets a default security descriptor.

lpThreadAttributes

Ignored. A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpThreadAttributes is NULL, the handle cannot be inherited.

bInheritHandles

Ignored. Set to true to indicate that each inheritable handle in the calling process is inherited by the launched process, or false to indicate that the handles are not inherited. The inherited handles have the same value and access rights as the original handles.

dwCreationFlags

A bitwise combination of the Win32 Process Creation Flags that control the priority class and the behavior of the launched process. For STARTUPINFOEX, the flag EXTENDED_STARTUPINFO_PRESENT is supported. See RtInitializeProcThreadAttributeList for more information.

lpEnvironment

Ignored. A pointer to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process.

lpCurrentDirectory

Ignored. The full path to the current directory for the process. The string can also specify a UNC path.

lpStartupInfo

A pointer to a STARTUPINFOEX structure that receives the startup information, if the STARTUPINFOEX flag exists under dwCreationFlags.

lpProcessInformation

Pointer to a PROCESS_INFORMATION structure that receives identification information about the new process.

Return Values

TRUE if the function succeeds, FALSE if the function fails.

To get extended error information, call GetLastError. RTX provides some custom error codes. See RTX Error Codes for more information.

Remarks

If you are launching an RTSS application that uses RTSS DLLs using RtCreateProcess, you must also launch the RTSS DLL using either RtCreateProcess or RtssRun with the /y option.

An RTSS process can be created and started through RTSSrun in command line windows. As an alternative way, RtCreateProcess can be used to create and start a new RTSS process through Win32 programs. RtCreateProcess creates processes dynamically.

It is possible for RtCreateProcess to fail to run a valid RTSS application if licensing information is not found or if the found licensing information is invalid. RTX has custom error codes related to licensing that can be returned from GetLastError to determine why an application failed to run. The RTX Subsystem must have a valid license and RTSS applications must be stamped with a compatible license before they can be run. See StampTool for more information on stamping applications. For more information on licensing products and components, see Licensing and Activation Overview.

When created, the new RTSS process handle receives full access rights. The handle can be used in any function that requires an object handle to that type. The RTSS process handle is returned in the PROCESS_INFORMATION structure. Refer to the Microsoft Developer Network Library for information on the PROCESS_INFORMATION structure.

The RTSS process is assigned a process identifier. The identifier is valid until the RTSS process terminates. It can be used to identify the RTSS process, or specified in RtOpenProcess to open a handle to the RTSS process. The RTSS process identifier is returned in the PROCESS_INFORMATION structure.

The preferred way to shut down an RTSS process is by using ExitProcess, because this function sends notification of approaching termination to all RTDLLs attached to the RTSS process. Other means of shutting down an RTSS process do not notify the attached RTDLLs.

The created RTSS process remains in the system until all threads within the RTSS process have terminated and all handles to the RTSS process and any of its threads have been closed through calls to RtCloseHandle.

If this handle is not needed, it is best to close it immediately after the process is created. When the last thread in an RTSS process terminates, the following events occur:

All objects opened by the RTSS process are implicitly closed.
The process's termination status (which is returned by RtGetExitCodeProcess) changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.
The RTSS process object is set to the signaled state, satisfying any threads that were waiting on the object.

You cannot set the stack size of the initial thread with this function. If you wished to change the main thread's stack size from the default you would need to rebuild your application and modify the stack size through linker option /STACK:commit. If you specify 0 (zero), the stack size defaults to 8192 bytes. The stack size is always rounded up to the next multiple of 1024. For example, if you request 8000 bytes, the allocated amount of memory would be 8192 bytes.

IMPORTANT! In the RTSS environment, the stack cannot grow.

Requirements

Header	Rtapi.h
Library	rtapi_w32.lib (Windows), Rtx_Rtss.lib (RTSS)